別名 ¶

別名用於表示檔案路徑或 URL，讓您不必在專案中硬式編碼絕對路徑或 URL。別名必須以 @ 字元開頭，才能與一般的檔案路徑和 URL 區分開來。未以 @ 開頭定義的別名將會加上 @ 字元作為前綴。

Yii 已經有許多預定義的別名可用。例如，別名 @yii 代表 Yii 框架的安裝路徑；@web 代表目前執行中的 Web 應用程式的基礎 URL。

定義別名 ¶

您可以呼叫 Yii::setAlias() 來為檔案路徑或 URL 定義別名

// an alias of a file path
Yii::setAlias('@foo', '/path/to/foo');

// an alias of a URL
Yii::setAlias('@bar', 'https://www.example.com');

// an alias of a concrete file that contains a \foo\Bar class
Yii::setAlias('@foo/Bar.php', '/definitely/not/foo/Bar.php');

注意：被別名化的檔案路徑或 URL 可能不一定需要參考現有的檔案或資源。

給定一個已定義的別名，您可以透過附加斜線 / 後面跟著一個或多個路徑段來衍生新的別名（無需呼叫 Yii::setAlias()）。透過 Yii::setAlias() 定義的別名會變成根別名，而從它衍生的別名則是衍生別名。例如，@foo 是根別名，而 @foo/bar/file.php 是衍生別名。

您可以使用另一個別名（根別名或衍生別名）來定義別名

Yii::setAlias('@foobar', '@foo/bar');

根別名通常在啟動引導階段定義。例如，您可以在入口腳本中呼叫 Yii::setAlias()。為了方便起見，應用程式 提供了一個名為 aliases 的可寫屬性，您可以在應用程式配置中配置它

return [
    // ...
    'aliases' => [
        '@foo' => '/path/to/foo',
        '@bar' => 'https://www.example.com',
    ],
];

解析別名 ¶

您可以呼叫 Yii::getAlias() 將根別名解析為它所代表的檔案路徑或 URL。相同的方法也可以將衍生別名解析為對應的檔案路徑或 URL

echo Yii::getAlias('@foo');               // displays: /path/to/foo
echo Yii::getAlias('@bar');               // displays: https://www.example.com
echo Yii::getAlias('@foo/bar/file.php');  // displays: /path/to/foo/bar/file.php

衍生別名所代表的路徑/URL 是透過將根別名部分替換為其在衍生別名中對應的路徑/URL 來決定的。

注意：Yii::getAlias() 方法不會檢查產生的路徑/URL 是否參考現有的檔案或資源。

根別名也可能包含斜線 / 字元。Yii::getAlias() 方法非常智慧，可以判斷別名的哪個部分是根別名，從而正確判斷對應的檔案路徑或 URL

Yii::setAlias('@foo', '/path/to/foo');
Yii::setAlias('@foo/bar', '/path2/bar');
Yii::getAlias('@foo/test/file.php');  // displays: /path/to/foo/test/file.php
Yii::getAlias('@foo/bar/file.php');   // displays: /path2/bar/file.php

如果 @foo/bar 未定義為根別名，則最後一個語句將顯示 /path/to/foo/bar/file.php。

使用別名 ¶

別名在 Yii 的許多地方都被識別，而無需呼叫 Yii::getAlias() 將它們轉換為路徑或 URL。例如，yii\caching\FileCache::$cachePath 可以接受檔案路徑和代表檔案路徑的別名，這要歸功於 @ 前綴，它可以將檔案路徑與別名區分開來。

use yii\caching\FileCache;

$cache = new FileCache([
    'cachePath' => '@runtime/cache',
]);

請注意 API 文件，以查看屬性或方法參數是否支援別名。

預定義別名 ¶

Yii 預定義了一組別名，以便輕鬆參考常用的檔案路徑和 URL

• @yii，BaseYii.php 檔案所在的目錄（也稱為框架目錄）。
• @app，目前執行中的應用程式的基礎路徑。
• @runtime，目前執行中的應用程式的執行時路徑。預設為 @app/runtime。
• @webroot，目前執行中的 Web 應用程式的 Web 根目錄。它是根據包含入口腳本的目錄來決定的。
• @web，目前執行中的 Web 應用程式的基礎 URL。它具有與 yii\web\Request::$baseUrl 相同的值。
• @vendor，Composer vendor 目錄。預設為 @app/vendor。
• @bower，包含 bower 套件的根目錄。預設為 @vendor/bower。
• @npm，包含 npm 套件的根目錄。預設為 @vendor/npm。

當您在入口腳本中包含 Yii.php 檔案時，會定義 @yii 別名。其餘的別名是在應用程式建構函式中應用應用程式配置時定義的。

注意：@web 和 @webroot 別名，如其描述所示，是在 Web 應用程式中定義的，因此預設情況下不適用於 主控台應用程式。

擴展別名 ¶

會自動為每個透過 Composer 安裝的擴展定義別名。每個別名都以擴展的根命名空間命名，如其 composer.json 檔案中所宣告，並且每個別名都代表套件的根目錄。例如，如果您安裝 yiisoft/yii2-jui 擴展，您將在啟動引導階段自動擁有別名 @yii/jui，相當於

Yii::setAlias('@yii/jui', 'VendorPath/yiisoft/yii2-jui');